/*
 * Copyright 2008 Max Kugland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
package org.splink.library.tree {
	import org.splink.library.IFinalizable;

	/**
	 * @author Max Kugland
	 */
	public interface INode extends IFinalizable {

		/**
		 * Adds a child to the list of children for this <code>INode</code>. 
		 * 
		 * @param child a <code>INode</code> object to add.
		 * @return the added <code>INode</code>
		 */
		function add(n : INode) : INode;
		
		/**
		 * Removes a child from the list of children for this <code>INode</code>. 
		 * 
		 * @param child a <code>INode</code> object to remove.
		 * @return the removed <code>INode</code>
		 */
		function remove(n : INode) : INode;

		/**
		 * Returns an <code>Array</code> which contains the children of the <code>INode</code>
		 * If there are no children an empty <code>Array</code> is returned. 
		 * 
		 * @return the children of this <code>INode</code>
		 */
		function get children() : Array;

		/**
		 * Returns <code>true</code> if the <code>INode</code> has no children.
		 * 
		 * @return true if this <code>INode</code> has no children 
		 */
		function get isLeaf() : Boolean;		

		/**
		 * @return the data hold by this <code>INode</code>
		 */
		function get data() : *;

		/**
		 * Sets data for this <code>INode</code>.
		 * 
		 * @param data
		 */
		function set data(data : *) : void;

		/**
		 * Returns the <code>INode</code>'s layer.The deeper the <code>INode</code> is in the tree, 
		 * the higher it's layer value is. The root <code>INode</code> which has no parent node 
		 * has the layer value '0' It's children have the layer value '1' and their children's 
		 * layer value is '2' and so on.
		 * 
		 * @return this <code>INode</code>'s layer
		 */
		function get layer() : uint;

		/**
		 * @return this <code>INode</code>'s parent <code>INode</code>
		 */
		function get parent() : INode;

		/**
		 * Sets this <code>Node</code>'s parent. As the parent <code>INode</code> is also set 
		 * through the constructor, this method can be handy when reparenting the <code>INode</code>
		 * 
		 * @param parent this <code>Node</code>'s parent <code>INode</code>
		 */
		function set parent(p : INode) : void;

		/**
		 * @return the id of this <code>INode</code>
		 */
		function get id() : String;
	}
}
